home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW noweb 2.7 / src / xdoc / noweb.txt < prev    next >
Encoding:
Text File  |  1995-05-30  |  7.6 KB  |  199 lines  |  [????/????]
  1.  
  2.  
  3.  
  4. NOWEB(1)                                                 NOWEB(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        noweb - a simple literate-programming tool
  9.  
  10. SSYYNNOOPPSSIISS
  11.        nnoowweebb [--tt] [--oo] [--LL_f_o_r_m_a_t] [--mmaarrkkuupp _p_a_r_s_e_r] [file] ...
  12.  
  13. DDEESSCCRRIIPPTTIIOONN
  14.        _N_o_w_e_b  is  a  literate-programming  tool like _F_u_n_n_e_l_W_E_B or
  15.        _n_u_w_e_b_, only simpler.  A _n_o_w_e_b file contains program source
  16.        code   interleaved  with  documentation.   When  _n_o_w_e_b  is
  17.        invoked, it writes the program source code to  the  output
  18.        files  mentioned  in  the  noweb file, and it writes a _T_e_X
  19.        file for typeset documentation.
  20.  
  21.        For more flexibility, consider _n_o_t_a_n_g_l_e_(_1_) and _n_o_w_e_a_v_e_(_1_)_.
  22.  
  23. FFOORRMMAATT OOFF NNOOWWEEBB FFIILLEESS
  24.        A  _n_o_w_e_b file is a sequence of _c_h_u_n_k_s_, which may appear in
  25.        any order.  A chunk may  contain  code  or  documentation.
  26.        Documentation chunks begin with a line that starts with an
  27.        at sign (@) followed by a space or newline.  They have  no
  28.        names.  Code chunks begin with
  29.        <<_c_h_u_n_k _n_a_m_e>>=
  30.        on  a  line by itself.  The double left angle bracket (<<)
  31.        must be in the first column.  Chunks are terminated by the
  32.        beginning  of  another  chunk,  or by end of file.  If the
  33.        first line in the file does not mark the  beginning  of  a
  34.        chunk,  it is assumed to be the first line of a documenta-
  35.        tion chunk.
  36.  
  37.        Documentation chunks contain text that is copied  verbatim
  38.        to  the  _T_e_X  file  (except for quoted code).  _n_o_w_e_b works
  39.        with _L_a_T_e_X; the first documentation chunk must  contain  a
  40.        _L_a_T_e_X \\ddooccuummeennttssttyyllee command with the nnoowweebb document-style
  41.        option.  It must also  contain  a  _L_a_T_e_X  \\bbeeggiinn{{ddooccuummeenntt}}
  42.        command.
  43.  
  44.        Code  chunks contain program source code and references to
  45.        other code chunks.  Several code chunks may have the  same
  46.        name;  _n_o_w_e_b  concatenates  their definitions to produce a
  47.        single chunk, just as other literate-programming tools do.
  48.        _n_o_w_e_b  looks  for  chunks that are defined but not used in
  49.        the source file.  If the name of such a chunk contains  no
  50.        spaces,  the chunk is an ``output file;'' _n_o_w_e_b expands it
  51.        and writes the result onto the file of the same  name.   A
  52.        code-chunk  definition is like a macro definition; it con-
  53.        tains references to other  chunks,  which  are  themselves
  54.        expanded,  and so on.  _n_o_w_e_b's output is readable; it pre-
  55.        serves the indentation of expanded chunks with respect  to
  56.        the chunks in which they appear.
  57.  
  58.        If  a  star (**) is appended to the name of an output file,
  59.        _n_o_w_e_b includes line-number information as specified by the
  60.        --LL_f_o_r_m_a_t option (or for C if no --LL_f_o_r_m_a_t option is given).
  61.  
  62.  
  63.  
  64.                           local 4/19/93                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. NOWEB(1)                                                 NOWEB(1)
  71.  
  72.  
  73.        The name itself may not contain shell metacharacters.
  74.  
  75.        Code may be quoted within documentation chunks by  placing
  76.        double  square brackets ([[[[_._._.]]]]) around it.  These double
  77.        square brackets are used to give the  code  special  typo-
  78.        graphic  treatment  in  the _T_e_X file.  If quoted code ends
  79.        with three or more  square  brackets,  _n_o_w_e_b  chooses  the
  80.        rightmost  pair,  so that, for example, [[[[aa[[ii]]]]]] is parsed
  81.        correctly.
  82.  
  83.        If double left and right angle brackets  are  not  paired,
  84.        they  are  treated  as literal <<<< and >>>>.  Users can force
  85.        any such brackets, even paired brackets, to be treated  as
  86.        literal by using a preceding at sign (e.g. @@<<<<).
  87.  
  88.        Any  line beginning with `@@ ' terminates a code chunk, but
  89.        if the line has the form
  90.        @@ %%ddeeff _i_d_e_n_t_i_f_i_e_r_s
  91.        it is taken to mean that the preceding chunk  defines  the
  92.        identifiers  listed  in  _i_d_e_n_t_i_f_i_e_r_s_.   This list contains
  93.        identifiers separated by whitespace; any sequence of  non-
  94.        white  characters may be an identifier.  _n_o_w_e_b uses a sim-
  95.        ple heuristic to avoid recognizing  identifiers  that  are
  96.        substrings of other identifiers.
  97.  
  98. OOPPTTIIOONNSS
  99.        --tt     Suppress generation of a _T_e_X file.
  100.  
  101.        --oo     Suppress generation of output files.
  102.  
  103.        --LL_f_o_r_m_a_t
  104.               Use  _f_o_r_m_a_t  to  format line-number information for
  105.               starred output files.  (If the option is omitted, a
  106.               format  suitable  for  C  is  used.)   _f_o_r_m_a_t is as
  107.               defined by _n_o_t_a_n_g_l_e_(_1_)_;
  108.  
  109.        --mmaarrkkuupp _p_a_r_s_e_r
  110.               Use _p_a_r_s_e_r to parse the input file.  Enables use of
  111.               noweb tools on files in other formats; for example,
  112.               the nnuummaarrkkuupp parser  understands  _n_u_w_e_b_(_1_)  format.
  113.               See  _n_o_w_e_b_f_i_l_t_e_r_s_(_1_)  for  more  information.   For
  114.               experts only.
  115.  
  116. BBUUGGSS
  117.        Ignoring unused chunks whose names  contain  spaces  some-
  118.        times causes problems, especially in the case when a chunk
  119.        has multiple definitions and one is misspelled;  the  mis-
  120.        spelled  definition  will be silently ignored.  _n_o_r_o_o_t_s_(_1_)
  121.        can be used as a sanity checker to catch this sort of mis-
  122.        take.
  123.  
  124.        _n_o_w_e_b  requires  the  new  version  of  _a_w_k_, assumed to be
  125.        called _n_a_w_k_.  DEC _n_a_w_k has a bug in that that causes prob-
  126.        lems  with  braces in _T_e_X output.  GNU _g_a_w_k is reported to
  127.  
  128.  
  129.  
  130.                           local 4/19/93                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. NOWEB(1)                                                 NOWEB(1)
  137.  
  138.  
  139.        work.
  140.  
  141.        The default _L_a_T_e_X pagestyles don't set the  width  of  the
  142.        boxes  containing  headers  and footers.  Since _n_o_w_e_b code
  143.        paragraphs  are  extra  wide,  this  _L_a_T_e_X  bug  sometimes
  144.        results  in extra-wide headers and footers.  The remedy is
  145.        to  redefine  the  relevant  ppss@@**  commands;  ppss@@nnoowweebb  in
  146.        nnoowweebb..ssttyy can be used as an example.
  147.  
  148. SSEEEE AALLSSOO
  149.        _n_o_t_a_n_g_l_e_(_1_)_, _n_o_w_e_a_v_e_(_1_)_, _n_o_r_o_o_t_s_(_1_)_, _n_o_u_n_t_a_n_g_l_e_(_1_)_, _n_o_w_e_b_-
  150.        _s_t_y_l_e_(_1_)_, _n_o_w_e_b_f_i_l_t_e_r_s_(_1_)_, _n_u_w_e_b_2_n_o_w_e_b_(_1_)
  151.        Norman Ramsey, _L_i_t_e_r_a_t_e _p_r_o_g_r_a_m_m_i_n_g _s_i_m_p_l_i_f_i_e_d_, _I_E_E_E _S_o_f_t_-
  152.        _w_a_r_e 11(5):97-105, September 1994.
  153.  
  154. AAUUTTHHOORR
  155.        Norman    Ramsey,   Bellcore.    Internet   address   nnoorr--
  156.        mmaann@@bbeellllccoorree..ccoomm.
  157.        Noweb              home              page               at
  158.        ffttpp::////bbeellllccoorree..ccoomm//ppuubb//nnoorrmmaann//wwwwww//nnoowweebb//iinnttrroo..hhttmmll.
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                           local 4/19/93                         3
  197.  
  198.  
  199.